Description

Adds HoverController, a Lit ReactiveController that centralises hover and keyboard-focus event wiring for 2nd-gen components that use the native Popover API (Tooltip, and any future popover-adjacent component).

What it provides

• Warm-up / cooldown timing — the popover opens only after the pointer has rested on the trigger for delay ms; leaving starts a matching cooldown. delay="0" opens and closes synchronously.
• Warm-state acceleration — once any instance of a component type warms up, subsequent hovers on the same type open immediately without re-timing.
• WCAG 1.4.13 pointer bridge — moving the pointer from the trigger into the popover cancels the cooldown, satisfying the "hoverable" requirement so users can interact with popover content.
• Keyboard focus priority — Tab focus opens immediately and suppresses all pointer-driven timers until focusout.
• Pointer-click exclusion — a pointer click does not open the popover. popover="auto" fires a light dismiss on pointerdown (the trigger is outside the popover surface); opening on the subsequent focusin would cause a visible flash. The controller detects this event sequence and skips the open.
• disabled / manual guards — re-evaluated live on every host update, no page reload required.

Basic usage

import { LitElement, type PropertyValues } from 'lit';
import { property } from 'lit/decorators.js';
import {
  HoverController,
  type HoverControllerHost,
} from '@spectrum-web-components/core/controllers/hover-controller.js';

class SwcTooltip extends LitElement implements HoverControllerHost {
  @property({ type: Number }) delay = 1500;
  @property({ type: Boolean }) manual = false;
  @property({ type: Boolean }) disabled = false;

  private triggerElement: HTMLElement | null = null;

  private readonly hoverController = new HoverController(this, {
    warmStateKey: 'swc-tooltip',
  });

  protected override updated(changes: PropertyValues): void {
    super.updated(changes);
    if (changes.has('triggerElement')) {
      this.hoverController.setTarget(this.triggerElement ?? null);
    }
  }
}

Method

Constructor options

HoverControllerHost interface

The controller does not resolve trigger elements, set ARIA attributes, or dispatch lifecycle events — those remain the consuming component's responsibility.

Motivation and context

Tooltip, and any future component that uses popover="auto", requires identical hover/focus logic. Extracting it into a shared controller keeps that logic in one place and tested independently before any consuming component is built.

Related issue(s)

• fixes SWC-2211

Author's checklist

• I have read the CONTRIBUTING and PULL_REQUESTS documents.
• I have reviewed at the Accessibility Practices for this feature, see: Aria Practices
• I have added automated tests to cover my changes.
• I have included a well-written changeset if my change needs to be published. (internal-only controller for now; no changeset)
• I have included updated documentation if my change required it.

Reviewer's checklist

• Includes a Github Issue with appropriate flag or Jira ticket number without a link
• Automated tests cover all use cases and follow best practices for writing
• Validated on all supported browsers

Manual review test cases

• Warm-up and cooldown

  1. Open the Hover controller Storybook story
  2. Hover "Trigger A" and hold until the tooltip appears (250 ms demo delay)
  3. Move immediately to "Trigger B"; expect it to open without delay (warm state)
  4. Leave trigger B and wait ~300 ms; expect tooltip to close
  5. Hover "Trigger B" again; expect it to require the full 250 ms warm-up (state has cooled)

• WCAG 1.4.13 pointer bridge

  1. Open the "WCAG 1.4.13 pointer bridge" story
  2. Hover the trigger until the tooltip appears
  3. Move the pointer from the trigger into the tooltip bubble without pausing outside
  4. Expect the tooltip to stay open indefinitely

• Keyboard focus

  1. Open the "Keyboard focus opens immediately" story
  2. Tab to the button; expect the tooltip to open at once (no delay)
  3. While focused, move the pointer off the button; expect tooltip to remain open
  4. Tab away; expect tooltip to close immediately

• Pointer-click focus does not open

  1. Open the Playground story with delay=1500
  2. Click the trigger button without hovering first
  3. Expect no tooltip to appear (click does not trigger focus-open)

Device review

• Did it pass in Desktop?

Accessibility testing checklist

• Keyboard (required — document steps below)

  1. Open the "Keyboard focus opens immediately" story
  2. Press Tab to move focus to the trigger button
  3. Expect tooltip to open immediately without warm-up delay
  4. Move pointer away from trigger while focused; expect tooltip to remain open
  5. Press Tab again to move focus away; expect tooltip to close immediately
  6. Confirm focus indicator is visible on the trigger throughout

• Screen reader (required — document steps below)

  1. HoverController does not set ARIA attributes directly; consuming components (e.g. Tooltip) are responsible for wiring aria-describedby and roles